Note: This help file is the most
complex one of the bunch. This is because using variables is an
extremely powerful thing. While it may seem intimidating at first, it's very easy
once you get the hang of it. Print the page out and read it at your leisure,
paying special attention to the examples. After a small bit of practice,
you will be making complex events and using variables to do things you never
thought possible before.
Portal© variables give you more
functionality over your mudding experience than just about any other
feature. When used in combination with
other features such as aliases, macros,
events, etc, the possibilities are endless. This files has five major sections:
variables overview, the set function, the if command, the system command and
then a section of examples for each.
Using variables in text and
commands is performed by simply adding the @ symbol before the variable, such
as @aaa. If the text option for that
command (program options screen) is checked for the Var column, the variable
will be replaced by the value. For
example, if @aaa=5, the command "say @aaa" would result in "say 5"
instead.
Note: To use the literal name of the
variable in a line, simply add another @ before the normal @. So in the above example, "say @@aaa" would result in
"say @aaa" instead. This is
useful when you want variables to change as a result of an if statement for
example. Using three @ symbols will
evaluate the variable and put the @ symbol before the result. So, if @aaa=50, "say @@@aaa" would
result in "say @50" instead.
Variables come in two distinct
kinds: User-Defined and System-Resident.
Variables
Overview
User-Defined Variables
These are declared in the variables
screen. These variables can
be named as the user desires (with some limitations) and can be created and
deleted on request.
System-Resident Variables
These variables work exactly
like User-Defined Variables, but are permanently assigned to the system and
cannot be deleted. They are designed
for use as a kind of “instant buffer” when used with events and event commands
as they do not need to be declared.
System Variables
These variables are used for
things in Portal© such as the HPBars and
gauges and stuff. When you assign a
value to any system variable, the program automatically processes the tasks
assigned to that variable. For example,
if you assign a value to the @HP variable, the HP gauge will be updated
accordingly and any appropriate status events will be fired off etc. Each of these variables are query-able as
they are set-able.
Portal© System Variables
@HP Hit points
@MAXHP Hit point maximum
@SP Spell points
@MAXSP Spell point maximum
@GP1 Guild points 1
@MAXGP1 Guild point 1 maximum
@GP2 Guild points 2
@MAXGP2 Guild point 2 maximum
@ENEMY Enemy health %
@ENAME Enemy name (used with the Imagery)
@GLINE1 Displays <string> in Guild line 1 (left side
of HP3 Bar)
@GLINE2 Displays <string> in Guild line 2 (right side of HP3
Bar)
@CAPTION Changes/references the caption of the main
screen
Note: The @GLINE1 and @GLINE2 values
are saved literally. That is, the color
codes are saved as raw text. So, if the
left side of the HP3 bar had the word “Danger” in red, the value currently
contained in @GLINE1 would be <rDanger>.
See the Appendix at the end of this file for more information on
coloring the glines.
The ;process Command and the Set() Function
Processing variables are done in two basic ways; the ;process command and the set() function.
The ;process command allows you
access to many math and string manipulation functions as described below. It consists of three parts, the Operand, the
Operator and the Expression, with no spaces between the three components.
;process
<Operand><Operator><Expression>
Note: You can use ";compile" in place of ";process" if you desire.
The set() function is almost identical to the ;process command, except for two distinct differences:
The set() function can be used with and within other numeric and string functions (such as math(), cap(), etc.)
The set() function returns a value which can be then be used in string concatenation or numeric formulas
set(<Operand><Operator><Expression>)
Think of the differences between the two formats this way. If you want to just set a variables value in a "behind the scenes" kind of way without returning or displaying anything, you would use the ;process command. If, however, you wanted to not only change a variable's value, but then immediately use it in a calculation you are designing, then you would use the set() function. Experience in using the two formats will quickly guide you in knowing which one to use at which time.
One aspect of variables is that
variables are stings or integers, depending on how you use them. If you process a string or a integer as a
string, it will act as a string. If you
process an integer or a string as an integer, it will treat integers normally
and strings as 0. When dividing, any
zeros are changed to 1 (to prevent division by 0) and any remainders are
truncated.
The
Operand
The operand is the left side of
the "equation" in a process.
This is the variable or evaluator that receives the value of the
process. The operand must have the @ symbol
in front. A simple example of operand
usage of the variable "blah" is ;process @blah=4. This assigns 4 to the variable blah.
The Operand can be a variable
or an evaluator. Variables (either
user-defined or system-resident) can be can be used on the left side of the
operator, as part of the expression or both.
System Evaluators can only be used on the left side of the operator. They cannot be used as part of the
expression. System References are the
opposite, they can only be used as part of the expression, not the operand
(think: read-only).
Portal© System Evaluators
@SOUND=<filename>
Plays the .wav file located in ...\Portal\media\sounds\<filename>.wav.
If you wish, you can use the
full path to the .wav file.
@MUSIC=<filename>~<repeat>
Plays the music file located in ...\Portal\media\sounds\<filename>
The file can be any MIDI
supported format (*.MID, *.RMI, etc.) or *.MP3 file.
If you include a <repeat>
value of “true” the music file will automatically repeat when it finishes its
cycle. This value is optional.
@IMAGE=<filename>~<label>
Displays the .BMP (bitmap) file located in
...\Portal\media\images\<string>.BMP.
If no .BMP file exists, it will
then try and load look for a .GIF file of the same name (...\Portal\media\images\<string>.GIF). The
<label> will appear on the Imagery label. This value is optional.
Displays the .AVI (movie) file
located in ...\Portal\media\images\<filename>.AVI.
The <label> will appear
on the Imagery label. This value is optional.
@TELL=<is
it from me?>~<other person>~<message>
Adds to the Tell Monitor. All values are required, separated by ~.
<from me?> Whether the tell is to me (nothing) or
from me (x)
<other person> Name of the other person the tell is
to/from
<message> The message text
Ex: Tell from me to Bob: x~Bob~Hey Bob!
Ex: Tell from Bob to me: ~Bob~Bob:
Hi! How's it going?
To setup
to have tells routed to the tell monitor, basically, set up an event "*
tells you: *" to parse to variables @AA and @BB. Then, for the action, setup ";process @TELL=~@AA~@BB" It's that simple.
@CHAT=<command>~<chat
line>~<who chatted>~<message>
Adds to the Chat Monitor. All values are required, separated by ~.
<command> Command to invoke the chat line (talk,
chat, speak, etc.)
<chat line> Title of the chat line (must be
unique)
<who chatted> Name of the person who chatted
<message> The message text
Ex: gtalk~Guild Line~Bob~Hey guild! How's it going?
@MWCOMBAT=<string>
Combat event message window (HP4 Bar)
@MWGUILD=<string>
Guild event message window (HP4 Bar)
@AUTOTYPER=<string>
Appends <string> to the currently
open Autotyper file. (opens one if
necessary)
You can include the format #|<string> as well to specify a particular Autotyper file. For example, “;process @AUTOTYPER=3|Blah” will append “Blah” to the 3rd Autotyper file.
@SYSTEM=<string>
Appends <string> as a new system message displayed in the System Messages screen
@EXECUTE=<string>
Attempts to (externally to Portal©) execute the filename <string>
System References
@TICKER
Returns the current ticker
value.
@TIME
Returns the current time value.
@DATE
Returns the current date value.
@CHARTING
Returns 1 if charting, 0 if not
charting.
@FOLLOWING
Returns 1 if following, 0 if not
following.
@ROOM
Returns the current value of
the room string (which appears in the status bar of Portal enhanced MUDs)
The
Operator
The operator is the middle of a
process command. Most often, the
operator is a = symbol. The operator
tells the program how you are going to assign the expression to the operand. The different operators are described below.
= Assigns expression to operand
+= Adds expression to operand, then assigns the result to operand
-= Subtracts expression from operand, then assigns the result to
operand
*= Multiplies expression and operand, then assigns the result to
operand
/= Divides operand by expression, then assigns the result to
operand
++ Increments operand by 1, then assigns the result to operand
-- Decrements operand by 1, then assigns the result to operand
The
Expression
Expressions can be direct
values or one of the many functions provided below. Direct values or functions can contain variables, but the
variables must be prefixed by the @ symbol to identify them as variables and not
just text. Before the expression is
assigned to the operand, all variables will be replaced by their current
values.
You can use as many functions
per process command as you desire, compounding them as you like, but spaces are
not allowed (they will be considered part of a string). For example, you can ;process @blah=cap(dl(abcd)) and end up with the variable blah assigned with Bcd.
Note: Functions can be used in any
command as well (assuming you have the f(x) option in that command’s Program
Options – Text Option checked). This
will allow you to operate on values and variables on the fly.
The functions available for use
in expressions are listed below.
Numeric
Functions
math(integer1+integer2)
Adds integer1 and integer2, then returns
the result
Ex: math(4+2) returns 6
Ex: math(4+@ccc) when ccc=50 returns 54
math(integer1-integer2)
Subtracts integer2 from integer1, then
returns the result
Ex: math(4-2) returns 2
Ex: math(4-@ccc) when ccc=50 returns -46
math(integer1*integer2)
Multiplies integer1 and integer2, then
returns the result
Ex: math(4*2) returns 8
Ex: math(4*@ccc) when ccc=50 returns 200
math(integer1/integer2)
Divides integer1 by integer2, then returns
the result (truncating any remainder)
Ex: math(4/2) returns 2
Ex: math(4/@ccc) when ccc=50 returns 0
Ex: math(10/4) returns 2
math(integer1%integer2)
Returns the modulus (remainder), if any,
after dividing integer1 by integer2
Ex: math(4%2) returns 0
Ex: math(10%4) returns 2
math(integer1^Integer2)
Raises integer1 to the integer2 power,
then returns the result
Ex: math(3^2) returns 9
Ex: math(4^3) returns 64
sqrt(integer)
Returns the square root of integer
(truncating any remainder)
Ex: sqrt(36) returns 6
Ex: sqrt(18) returns 4
random(integer)
Returns a random integer from 0 to
integer-1
Ex: random(50) returns a random value from
0-49
abs(integer)
Returns the absolute value of any integer
Ex: abs(-44) returns 44
sum(integer1,integer2,..,integerN)
Returns the sum of all integers
Ex: sum(10,20,30) returns 60
avg(integer1,integer2,..,integerN)
Returns the average of all integers
Ex: avg(10,20,30) returns 20
String
Functions
cap(string)
Capitalizes the first letter of string
Ex: cap(fish) returns Fish
Ex: cap(@aaa) when aaa=test returns Test
Ex: cap(fish@bbb) when bbb=head returns
Fishhead
CAP(string)
Capitalizes every letter in string
Ex: CAP(fish) returns FISH
Ex: CAP(@aaa) when aaa=test returns TEST
Ex: CAP(fish@bbb) when bbb=head returns
FISHHEAD
lc(string)
Forces every letter in string to
lower-case
Ex: lc(FISH) returns fish
Ex: lc(@aaa) when aaa=TEST returns test
Ex: lc(FiSh@bbb) when bbb=HeAd returns
fishhead
dl(string)
Deletes the leading character of string
Ex: dl(jump) returns ump
dt(string)
Deletes the trailing character of string
Ex: dt(jump) returns jum
cls(string)
Clears all leading spaces from string
Ex: cls( jump) returns jump
cts(string)
Clears all trailing spaces from string
Ex: cts(jump ) returns jump
cbs(string)
Clears both leading and trailing spaces
from string
Ex: cbs( jump
) returns jump
length(string)
Returns the length of string (number of
characters
Ex: length(hey there) returns 9
pos(substring,string)
Returns the position of substring within
string
If substring is not anywhere within
string, pos returns 0
Ex: pos(f,abcdefghi) returns 6
Ex: pos(uck,I suck) returns 4
Ex: pos(duck,I suck) returns 0
copy(string,start#,amount)
Returns the portion of string starting
with the start# character, amount characters long
Ex: copy(abcdefg,2,3) returns bcd
Ex: copy(abcdefg,1,4) returns abcd
Ex: copy(abcdefg,2,99999) returns bcdefg
delete(string,start#,amount)
Deletes amount characters starting with
start# from string
Ex delete(abcdefg,2,3) returns aefg
Ex delete(abcdefg,1,4) returns efg
Ex delete(abcdefg,2,99999) returns a
subs(stringtoreplace,newstring,string)
Substitutes all instances of
stringtoreplace in string with newstring
Ex: subs(x,a,xyz) returns ayz
Ex: subs( ,,a b c d e f) returns abcdef
Ex: subs(a,1,@test) when test=aardvark
returns 11rdv1rk
Note: Sometimes you might like to actually use the comma
character when manipulating strings using the string functions. Using the comma alone won’t work (as it’s
used to separate the different parts of functions), so Portal© provides you
with the literal comma character “\,” (backslash followed immediately by a
comma). Use the literal comma wherever
you want to end up with a regular comma.
While the “literal comma character” is really two characters, it’s
considered functionally to be only one character. This is important to remember when using functions like pos(),
copy() or delete(), as the exact location of a character is vital to these
function.
pos(substring,string) (using the literal comma character)
Returns the position of substring within
string
If substring is not anywhere within
string, pos returns 0
Ex: pos(f,abc\,defghi) returns 7
Ex: pos(\,,I\, suck) returns 2
Ex: pos(duck\,,I suck) returns 0
copy(string,start#,amount) (using the literal comma character)
Returns the portion of string starting
with the start# character, amount characters long
Ex: copy(ab\,cdefg,2,3) returns b,c
Ex: copy(\,abcdefg,1,4) returns ,abc
Ex: copy(abcdef\,g,2,99999) returns
bcdef,g
delete(string,start#,amount) (using the literal comma character)
Deletes amount characters starting with
start# from string
Ex delete(ab\,cdefg,2,3) returns adefg
Ex delete(\,abcdefg,1,4) returns defg
Ex delete(\,abcdefg,2,99999) returns ,
subs(stringtoreplace,newstring,string) (using the literal comma character)
Substitutes all instances of
stringtoreplace in string with newstring
Ex: subs(x,a,x\,yz) returns a,yz
Ex: subs( ,,a b c d e f) returns abcdef
Ex: subs(\,,,a,b,,,,,,c,,,d,e,f) returns
abcdef
Case
Functions
R(<value1>,<value2>,...,<valueN>)
Returns one of the values listed, randomly
selected.
Example:
R(grin,smile,dance)
Returns either grin, smile or dance,
completely by random choice
Case Expression
@(<value or
variable>,<case1>=<value1>,...,<caseN>=<valueN>)
Takes the <value or
variable> and compares it to the cases 1 to N. If a match occurs, the value associated with that case is
returned. If no match happens, valueN
(the last value) is returned.
Examples:
@(Death,Good=80,Bruises=40,Death=10)
returns 10
@(@status,Good=80,Bruises=40,Death=10)
when @status=Good, returns 80
when @status=Bruises, returns 40
when @status=Death, returns 10
@(@response,10=I'm feeling
pretty bad,30=I'm ok,50=I'm great,xxx=No clue)
when @response=10, returns I'm feeling pretty bad
when @response=30, returns I'm ok
when @response=50, returns I'm great
when @response is anything other than 10, 30 or 50, returns No
clue
Note: Just like with the string functions, case functions
allow you to use the \, character to force a literal comma where you need.
Date/Time
Functions
datetime(format)
Returns the current date/time as defined
by the format given. For format is
given as a combination of datetime format elements.
Basic Date/Time Format Elements
c (or empty) the full date as defined by your system
d day as a number without a
leading 0 (1-31)
dd day as a number with a
leading 0 (01-31)
ddd day as an abbreviation
(Sun-Sat)
dddd day as a full name
(Sunday-Saturday)
m month as a number without a
leading 0 (1-12)
mm month as a number with a
leading 0 (01-12)
mmm month as an abbreviation
(Jan-Dec)
mmmm month as a full name
(January-December)
yy year as a 2-digit number
(00-99)
yyyy year as a 4-digit number
(0000-9999)
h hour without a leading 0
(0-23)
hh hour with a leading 0
(00-23)
n hour without a leading 0
(0-59)
nn hour with a leading 0
(00-59)
s hour without a leading 0
(0-59)
ss hour with a leading 0
(00-59)
t the short time format as
defined by your system
tt the long time format as
defined by your system
am/pm Uses the 12-hour clock for the
preceding h or hh specifier, and displays 'am' for any hour before noon, and
'pm' for any hour after noon. The am/pm specifier can use lower, upper, or
mixed case, and the result is displayed accordingly
a/p Uses the 12-hour clock for
the preceding h or hh specifier, and displays 'a' for any hour before noon, and
'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed
case, and the result is displayed accordingly
/ date separator character
as defined by your system
: time separator character
as defined by your system
‘ ‘ or “ “ anything enclosed in quotes is
displayed literally
For the following
example, assume the current date/time as: April 7th 1971 at
10:32:00pm
datetime(mm/dd/yy)
Yields: 04/07/71
datetime(h:nn:ss
d/m/yy)
Yields: 10:32:00 4/7/71
datetime(‘Sometime
in ‘mmmm’ after ‘ham/pm)
Yields: Sometime in April after 10pm
The
If Command
The if command is basically a
prefix to any other command you with to execute. The command can be typed, autotyped, in an event action, an alias
command etc. It differs from a normal
command in that you assign a logical condition before it. For the command to execute, the logical
condition must be true. If the
condition is false, and there is also an else command defined, that command
will execute, otherwise nothing happens.
Processing the if command is done using the activator character (; is
used here as the default). The format
of the If command is described below.
;if
<Condition> then <Command>
OR
;if
<Condition> then <Command> else <Command2>
The “if” “then” and “else” words are literals and do
not change. <Command> or <Command2>
can be, as stated before, any command you would ever want to normally do –
entered as you would normally enter it.
The <Condition> element,
however, must be formatted as this.
<Operand1><Logic
Control><Operand2>
<Operand1>
and <Operand2> Any single
variable or value
<Logic
Control> Logic
used to compare the two operands
Available Logic Controls
= Operand1 equals Operand2
> Operand1 is greater than Operand2
< Operand1 is less than Operand2
>= Operand1 is greater than or equal to Operand2
<= Operand1 is less than or equal to Operand2
<> Operand1 is not equal to Operand2
When comparing two integers,
greater than will mean the higher number.
For example, 6 would be “greater than” 1 and 67 would be “less than”
101.
When comparing a string to a string, greater than will mean afterwards alphabetically. For example, cat would be “greater than” apple and fish would be “less than” zebra.
When comparing a string to an
integer (or vice-versa) the string will be considered 0.
Compounding Logic Statements
The condition can either be one
logical condition or many different ones compounded together.. You can compound your logic conditions by
using the logical functions and(), or() and not().
and(condition1,condition2)
·
If
both condition1 and condition2 are true, the and function is true
·
If
either condition1 or condition2 is false, the and function is false
or(condition1,condition2)
·
If
either condition1 or condition2 is true, the or function is true
·
If
both condition1 and condition2 are false, the or function is false
not(condition)
·
If
condition is true, the not function is false
·
If
condition is false, the not function is true
Examples
and(1=1,0=0) True because both
conditions are true
and(1=0,0=0) False because at least
one condition is false (the first one)
or(1=0,0=0) True because at least
one condition is true (the second one)
or(1=0,0=1) False because both
conditions are false
not(1=1) False, because the
not() function reverses what would normally be a true statement
or(1=0,not(0=1)) True because the second
condition is true (as a result of the not() function)
and(1=1,or(1=0,0=0)) True because the or() function is
true, as is the first condition of the and() function (which envelops the or()
function)
or(1=0,and(1=0,0=0)) False because the and() function is
false, as is the first condition of the or() function (which envelops the and()
function)
not(or(1=0,and(1=0,0=0))) True - It follows all of the above
example’s rules, but the not() function reverses the final result
The
System Command
The system commands allows you
to see a local display of variable processing, without sending anything to the
server. All variables and functions
will always be evaluated with this command and the result is printed to the display
in the system text colors.
For example, say you have the
variables xxx=50 and yyy=40. If you
then did the command: ;system avg(@xxx,@yyy), the text “System: 45” would be
displayed to the screen. This is
basically a handy way to preview variable/function usage before you send
anything to the server.
Variable Processing Examples
My MUD’s HP bar looks like [HP:100/100
SP:120/120]. How can I have, whenever
that appears, populate the numbers and neat little gauges on my HP1 and HP2 Bars?
1)
Set up an event for
[HP:*/* SP:*/*]. In the Select Variable
screen, select the following system variables in this order: @HP, @HPMAX, @SP,
@SPMAX
Now, how hard was that? You don’t even need any actions defined. That’s the beauty of system variables. All the processing for the gauges and
whatnot are done at the instant you assign a value to a system variable.
My MUD’s HP bar looks like [HP:100/100 SP:120/120
Enemy:<status>]. How can I have
Portal©, whenever that appears, populate the numbers and neat little gauges on
my HP1 and HP2 Bars?
ALSO, the enemy status ranges from “Good” to “Bleeding” to “Death” How can I populate those words into numeric
values to be used on the neat little enemy gauge?
1) Set
up an event for “[HP:*/* SP:*/* Enemy:*]”
In the Select Variable screen, select the following system variables in
this order: @HP, @HPMAX, @SP, @SPMAX, @AA
2)
In that event, create
the action ;process @ENEMY=@(@AA,Good=100,Bleeding=40,Death=10,else=100)
You just used a System-Resident Variable (AA) and the
Case Expression function to do that.
Neat huh?
Ok, in the above example, I also want the literal
enemy status to appear in my HP3 bar - in green if it’s “Good” and yellow if
it’s otherwise.
You would simply add the following two lines…
3)
Create another action
;if @AA=Good then ;process @GLINE1=<g@AA>) else set(@GLINE1=<y@AA>
I want to “tell bob hi!” whenever I see ”[Bob logs
in]” but I only want to do it once.
1)
Declare the variable:
sawbob that initializes to 0
2)
Set up an event for
“[Bob logs in]”
3)
In that event, create
one action for ;if @sawbob=0 then tell bob hi!
4)
Create another action
in that event for ;process @sawbob=1
I use darts to toss at my enemy, and I get the
message “You have 10 darts left” after I use one of them (10 as an
example). I want to be alerted visually
and by sound as to when my dart inventory hits 10.
1)
Declare the variable:
darts that initializes to 0
2)
Set up an event for
“You have * darts left”
3)
In that event, create one
action for ;if darts=10 then ;5 say I only have 10 darts!
4)
Create another action
in that event for ;if darts=10 then ;process @SOUND=beep
This is assuming you have “beep.wav” in your …Portal\media\sounds directory.
Appendix:
Coloring the GLine1 & GLine2
The glines appear on the HP3
Bar. The text that appears has a black
background and the font is colored white by default. While you cannot change the black background, you can change the
font color when setting it.
All you have to do is
encapsulate the text you desire to color in the format specified below. You can't use < or > anywhere in the
glines as normal text or it'll screw up.
If you already use < or > enclosures, you'll have to use something
else to encapsulate your data. All text
not enclosed in any color activators appear as white.
Format: <x><word>
<x> color code
<word> text to be colored (any length)
Valid Color Codes
y yellow
r red
b blue
g green (windows calls it lime)
c cyan (windows calls it aqua)
v violet (windows calls it fuchsia)
s silver (dim white)
Example 1: The red <rfox> jumped over the cyan
<cdog>
Display: The red fox jumped over the cyan dog
("fox" will appear in red,
"dog" will appear in cyan)
Example 2: Spells Activated: [<bshield>,<gmagic
missile>]
Display: Spells Activated: [shield,magic
missile]
("shield" will appear in
blue, "magic missile" will appear in green)
Example 3: Demon Follower's Health: <a95%>
Display: Demon Follower's Health: 95%
(The whole line appears in white)
Now, why would the 95% appear
all in white? Because "a" was
used, which is not a valid code.
We suggest you keep the number
of uses of the activator to under 10 per gline. That means under 10 uses of the <> pairings.